Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 003 / dgclip.arc / DG_DOC.TXT < prev next >

Wrap

Text File | 1985-08-15 | 20.8 KB | 508 lines

dGENERATE Documentation (Version 1.0: August, 1985) (Revised August 15, 1985) Copyright 1985, Tom Rettig Associates, All Rights Reserved 9300 Wilshire Boulevard, Suite 470, Beverly Hills, CA 90212 (213)272-3784 -- Source: BCR480 -- CompuServe: 75066,352 dGENERATE is a dBASE III screen and code generator written entirely in dBASE III. The generated code is intended to assist rather than replace the application programmer. dGENERATE produces simple, easy to understand algorithms because every programmer's needs are different, and there is no single algorithm that will work for everyone. One of dGENERATE's main features is that it is written in dBASE III and can be easily modified to generate any algorithm you like. Due to the variety of algorithms required for applications development, we prefer to maintain a library of routines and incorporate the generated code with the appropriate routine for each application. RIGHTS: You are encouraged to freely distribute copies of dGENERATE to anyone you choose, as long as you do not charge for it and the original copyright notice and registration information remain intact in both the code and documentation. You own the generated code just as if you wrote it yourself; use it however you like. You have the right to use portions of dGENERATE's source code, either modified or unmodified, in any original application of your own that does not directly compete with dGENERATE. We disclaim all liability and make no guarantee. You are invited to become a registered dGENERATE by sending fifteen dollars to us at the above address for which we will send you a disk containing the latest version of all the files listed below. Registration also entitles you to full technical support by telephone, mail, CompuServe, and the Source. Only if we have you on file can we notify you of updates, bug-fixes, and new dBASE-related software. Registration supports the development and marketing of inexpensive software via the "shareware" concept. Your registration makes an important contribution! We feel that dGENERATE belongs to the entire dBASE community, and your feedback is highly valued. If there is anything you think should be changed or added to the next version, please write us with your comments. The dGENERATE files are: Source code: dg_main.prg (7K) and dg_proc.prg (55K) Executes under dBASE III, any version greater than 1.1 RunTime+ linked: dg.prg (30K) Executes under dBASE III, any version greater than 1.1 or dBRUN Clipper compiled: dg.exe (160K) Executes under MS- or PC-DOS, version 2.0 or higher dg_clip.prg (55K) is the compilable source code for the Clipper version Database: dg.dbf One field 'dg_text', character 254 bytes Documentation: dg_doc.txt (20K) Announcement: about_us.txt (1K) INSTALLATION: "Install" simply means to copy the appropriate files onto your working disk. You only need to install the file or files that you will use. If you want to run source code, install both the main and procedure files. If you want to run the linked file, only install dg.prg. If you do not have a copy of dBASE III later than version 1.1, install only dg.exe. All versions of dGENERATE use the dg.dbf system database file. Once you have printed a copy of this documentation file, you do not need it on your disk. Hard Disk: This is the easiest way to use dGENERATE. Set your operating system "path" to the directory where dBASE III is installed (see your operating system manual). Now you can call dBASE from anywhere. Once in dBASE III, SET PATH TO the directory where dGENERATE is installed. Now you can use dGENERATE from anywhere that you can call dBASE. The files created by dGENERATE are always in the local directory. The editor (word processing software) you specify during <S>etup must be accessible from the current directory from which you entered dBASE III. Your editor must be able to find its overlay files when called from this directory. If it works from the operating system prompt where you enter dBASE, it should work in dGENERATE. Floppy Disk: One method is to place a copy of both dGENERATE and your editor on a separate disk which is placed in drive B and used as your development disk during the application's implementation. The other method is to create a new dBASE III System Disk Two. If enough of the optional files are removed from System Disk Two, both your editor and dGENERATE can be placed on it in drive A. In either of these floppy schemes, both the DOS file "Command.com" and the dBASE III overlay file "Dbase.ovl" must be on the disk in drive A. Your editor's overlay files must be on the drive where your editor knows to look for them. If your system has very little memory, you may get an "Insufficient Memory" error message from dBASE when it tries to RUN your editor. To correct this, you can add more memory to your system or use the compiled version of dGENERATE which requires much less memory than the versions that run under dBASE. SETUP: There are thirteen sets of parameters that can be changed in the setup module by selecting number six <S>etup on the main menu. 1. Characters that denote SAYs and GETs in a screen-form Default: SAY '}', GET '{' 2. Character that denotes memory variable in a screen-form Default: '~' (the tilde) 3. Size of screen-form in rows and columns Default: 24 rows, 80 columns 4. Relative or literal addressing in @ coordinates Default: Literal 5. Add the ruler line in screen-form or omit Default: Add 6. Set delimiters on or off Default: Off 7. Fill new screen form with blanks or omit Default: Omit 8. Display help screens or omit Default: Display 9. File extensions created by dGENERATE Default: Screen-form '.dgS' (Screen-form file), generated code '.dgP' (Program file), generated memvars '.dgM' (Memvar file) 10. Ruler line characters Default: Column zero '0', every ten columns thereafter '123456789.' 11. Delimiter characters Default: Left ':', right ':' 12. Marquee line character (ASCII value) Default: 61 ('=') 13. Filename of editor used to draw screen-forms Default: none (uses MODIFY COMMAND) dGENERATE relies on the word processing software you assign for all editing tasks. If you have assigned an editor in <S>etup, dGENERATE will RUN it for all <E>diting operations. If not, dGENERATE will call MODIFY COMMAND which will run either the built-in dBASE III word processor or the editor that has been assigned to WP in Config.db. Because the built-in dBASE III word processor wraps all lines at the 67th column and provides no way to disable this feature, it is most inconvenient for drawing screen-forms. The use of a more versatile editor is highly recommended. To use a memory-resident editor such as the one in SideKick, assign "INMEMORY" during <S>etup. This will prevent the automatic <E>dit after <C>reate. While at dGENERATE's main menu, call your editor the way you usually do instead of using the <E>dit procedure. Then save the file, exit the editor, and select <G>enerate to write the code. The "parameters line" is made up of these values and can be saved in the system database file. Part of the parameters line is stored in each newly created screen-form file to tell dGENERATE what parameters to use in generating code from each screen-form. Change parameters in <S>etup before <C>reating new screen-forms. Change parameters in existing screen-forms by <E>diting the parameters line in the screen-form itself. OPERATION: dGENERATE performs five distinct operations, each of which can be called from the main menu. 1. <C>reate a new screen-form 2. <E>dit an existing screen-form 3. <G>enerate code from a screen-form 4. <D>O (execute) a command file 5. Generate <M>emory variable code from a database file Some operations are called automatically from other operations. For example, if you create a new screen-form, you are automatically placed in it for editing. Code is automatically generated after editing a screen-form, and newly generated command files are automatically executed. General: If you are running dGENERATE under regular dBASE III, pressing the Escape key will SUSPEND dGENERATE and place you in the interactive mode of dBASE III. Type RESUME to return to dGENERATE. This is useful when you want to create a database file or test an expression without exiting and rebooting dGENERATE. If you SUSPEND while in dGENERATE's main menu, you must press a key after RESUMing in order to redisplay the menu. dGENERATE uses only one work area, the current one when dGENERATE is entered. However, because the RUN command is used for editing, we recommend that you close all open files before executing dGENERATE to avoid the possibility of corrupting them. dGENERATE creates temporary files during code generation, but erases them when finished or if aborted properly. These are not big, using one 255 byte record for each line in a screen-form, but there must be room on the default disk for this file and its index file (around 10K). The first release of dGENERATE does not check for adequate diskspace before creating its temporary files. dGENERATE variables all begin with 'dg_' or 'dl_' to avoid confusion with other variables on which you might use dGENERATE. Avoid naming memvars or fields beginning with 'dg_' or 'dl_' to prevent any conflict with dGENERATE. dGENERATE uses the following names for procedures. An attempt to <D>o a command file of the same name will have unpredictable results. Avoid the use of these names for screen-forms: abort, alt_file, config, crea_new, doer, editor, file_msg, fileprmt, generate, gen_entr, gen_menu, gen_rprt, helper, hlp_crea, hlp_doer, hlp_edit, hlp_gene, hlp_mgen, hlp_setu, hlp_togl, key_time, line_inc, marquee, mem_gen, pars_lit, pars_var, setup, set_if1, set_if2, set_if3, wait_msg, and write. There is a "time-out" feature in dGENERATE. If you leave dGENERATE inactive for three minutes while in the main menu, it will clear the screen body and prompt you to press any key to re-activate. If you are in a sub-menu, it will return to the main menu. Option 1: <C>reate a new screen-form dGENERATE places several items in a new screen form to set it up for your use. To understand these, we must first define the parts of a screen-form. Every screen-form has three parts, the header, the body, and the footer. The body is where you draw your screen or form. The header contains the ruler line, and the footer contains the variable definitions, code generating options, and parameters line. If the ruler-line flag is on, dGENERATE places a ruler on the first line in the screen-form to assist you in measuring columns and placing data. If the blank-fill flag is on, dGENERATE fills the body of the screen-form with blank spaces. If you reply that you want to add memvars from a database file when prompted, dGENERATE places the appropriate names in the definition table in the footer. Option 2: <E>dit a screen-form (or any text) file If you have specified the form width (columns) in <S>etup, the ruler line will be that exact width. Because it is the first line in the file, most editors will be positioned to it upon entering. Many editors allow you to set the working margins from any line on which the cursor appears. In WordStar, for example, you can set your working margins to the proper screen-form width by pressing Ctrl-OF (^OF) when the cursor is on the ruler line. You draw your screen-form by writing all literal prompts precisely where you want them to appear. Variables to be displayed with either a SAY or a GET are identified by the SAY or GET symbol immediately followed by a single character "definition symbol" of your choice. For example: Name: }a Address: {b City: {c The GET and SAY symbols '{' and '}' cannot be used for anything else. If you need to use them in the screen-form for something else, change the symbols first in <S>etup. The definition symbols 'a', 'b', and 'c' are defined in the definitions table below the screen body: dgDEFINE a Name b Address c City If you want to have a better idea of what your screen or form will look like while you are drawing it, you can follow the definition symbol with any combination of characters. All characters immediately following a definition symbol are ignored until a space is encountered. For example: Name: }Full_name_goes_here-------------- Address: {9300_Wilshire_Boulevard,Suite_470 City: {*--------------------| State:}S Memvars may be specified in the definitions table to take the place of field names: dgDEFINE F m_name ~ Name 9 m_address ~ Address * m_city ~ City S m_state ~ State The definitions table may simply contain expressions instead of variables unless a GET is being used on that symbol: dgDEFINE T TIME() D DATE() & SPACE(20) PICTURE and FUNCTION phrases may be added and there are no restrictions about spacing other than beginning with the definition symbol in the first column and placing all definitions in the "definition table." The definition table begins with the word 'dgDEFINE' on a line in the first column. The next line is an example syntax of a definition. All definitions are placed one per line immediately following the definition table's example syntax: dgDEFINE -- Example syntax follows <definition symbol> [<memvar> ~] <expression> [PICTURE <phrase>] 1 "All definitions go here" 2 m_var ~ "and here" PICTURE "AAAXAAAA" 3 "and so on..." FUNCTION "!" a "Note that lowercase and" A "uppercase are different symbols." If you answered that you want memvars added from a database file during the <C>reate a screen-form process, the definition table will look like this: dgDEFINE m_name ~ Name m_address ~ Address m_city ~ City You simply add the definition symbol that you use in the screen body to the first column of each definition. You can also add PICTURE or FUNCTION clauses and && comments if desired: dgDEFINE 1 m_name ~ Name FUNCTION "!" && uppercase key expression 2 m_address ~ Address 3 m_city ~ City All definitions must fit on one line, and cannot be continued with a semicolon. Leave a blank line after your definitions are completed. dGENERATE options are dgFILE, dgENTRY, dgMENU, and dgREPORT. Options can be declared anywhere in a screen-form as long as they begin a line in the first column. Only one dgFILE may be declared in each screen-form. If more than one is declared, only the first will be used. Only one of the dgENTRY, dgMENU, or dgREPORT options may be declared. If more are declared, only the first in this order of precedence will be used: dgENTRY, dgMENU, dgREPORT. dgFILE <database filename> Writes the code for opening and closing a database file. dgENTRY Writes the algorithm for data entry or edit. dgMENU Writes the algorithm for menu driven user selections. Uses INKEY() algorithm, and you specify the characters for each CASE statement on a separate line below the dgMENU declaration. dgREPORT Writes the algorithm for printed reports. Requires use of a database file (can use dgFILE). dgFILE takes only the filename, not the DBF extension: dgFILE Names dgMENU requires allowable characters for each CASE be listed without delimiters on a new line directly below the dgMENU declaration. Each line represents the keys that may be pressed to select one option from the menu: dgMENU Aa1 Bb2 Cc3 Qq dgREPORT writes code that uses the printer. Be sure your printer is on line when using this option or executing the generated code. Maximum form size is 254 columns by 999 rows. GETs are automatically converted to SAYs so that you can re-use screen- forms originally drawn for data entry. Option 3: <G>enerate code from screen-form Sit back and relax while dGENERATE does the work. Part of the code written is to initialize a variable called 'undefined' with three asterisks. This prevents a generated program from crashing when a memvar initialization is overlooked. If the relative addressing flag is on, dGENERATE will write the @ coordinates using the ROW() function. PROW() is used if it is declared as a report with dgREPORT. Only ROW() and PROW() are generated as functions, and literal addresses are used in place of COL() and PCOL() regardless of the flag status. Option 4: <D>o a command file "***" appearing in your screen or form means that a variable has not been properly defined or initialized. When DOing a newly generated command file, dGENERATE displays the screen and then does an invisible WAIT before returning to the Main Menu. This is necessary in order to see the results of your screen-form, but provides no prompt to press a key unless you have included one in your screen. Remember to press a key to return to the menu after you have seen your generated screen displayed. If a DO file crashes, select SUSPEND, then type RETURN and RESUME. This will place you back in dGENERATE's Main Menu. This option is not available in the compiled version of dGENERATE because the generated dBASE code needs a dBASE interpreter to run, or it must be compiled first. The compiled dGENERATE offers access to DOS in this place where the generated code can be compiled or the dBASE interpreter can be called. None of this is automated because the code is likely to be incorporated with other code before compiling is desirable. Option 5: <M>ake memvars from fields Just give dGENERATE the name of a database file, and it will create memvar names from the field names and write initialization and REPLACE commands. Two kinds of initialization statements are generated. One from the field names: m_name = Name m_start_da = Start_date m_amount = Amount The other from expressions: m_name = SPACE( 35) m_start_da = CTOD(" / / ") m_amount = 0000.00 The REPLACE statements: REPLACE Name WITH m_name REPLACE Start_date WITH m_start_da REPLACE Amount WITH m_amount This code is not intended to run as it stands. It is meant to be incorporated into the code that you write for each application. Note that the memory variable names only use the first eight characters of the field names. When CREATing your database files, keep significant letters within the first eight letters: 'Fieldname1' and 'Fieldname2' both generate 'm_fieldnam' 'Field_1' and 'Field_2' generate 'm_field_1' and 'm_field_2' TECHNICAL SUPPORT: Electronic mail on CompuServe or the Source is the best way. Regular postal mail is good if your needs are not immediate. We also offer support by telephone, but cannot guarantee that a technical person will be available when you call. However, a programmer will return your call the same or following working day. All long distance support calls are returned COLLECT in order to keep the price of dGENERATE as low as possible. Remember, we only charge fifteen dollars. Please do NOT call Ashton-Tate or Nantucket for dGENERATE support. They are very busy supporting their own products. TRADEMARKS: Ashton-Tate: dBASE, dBASE III, RunTime+ Borland: SideKick IBM: PC-DOS MicroPro: WordStar Microsoft: MS-DOS Nantucket: Clipper Tom Rettig Associates: dGENERATE *** EOF: dGENERATE Documentation ***